package sjtu.rfid.rri.services.queue;

/**
 * This interface defines the basic operations of Queue Factory.
 * 
 * @author jinghao
 * 
 */

public interface QueueFactory {

	/**
	 * Get an existing Queue Object by the specified name or creates a new one
	 * using the specified name.
	 * 
	 * @param queueDescription
	 *            Specify the queue description. e.g.
	 *            "activequeue:queuename;queuesize=10"
	 * @return a Queue Object
	 * @throws QueueTypeNotFoundException
	 *             if the queue type specified in queueDescription can't be
	 *             found.
	 * @throws QueueException
	 *             if there exist some error when creating the queue.
	 */
	public Queue createQueue(String queueDescription)
			throws QueueTypeNotFoundException, QueueException;

	/**
	 * Adds a queueListener to the set of queueListeners for this queue,
	 * provided that it is not the same as some queueListener already in the
	 * set. The order in which notifications will be delivered to multiple
	 * queueListeners is in the order of adding in.<br>
	 * This operation may create a new queue if there exists no such queue
	 * following the queueDescription.
	 * 
	 * @param queueDescription
	 *            Specify the queue description. e.g.
	 *            "activequeue:queuename;queuesize=10"
	 * @param queueListener
	 *            an QueueListener to be added.
	 * @throws NullPointerException
	 *             if the parameter queueListener is null.
	 * @throws QueueTypeNotFoundException
	 *             if the queue type specified in queueDescription can't be
	 *             found.
	 * @throws QueueException
	 *             if there exist some error when creating the queue.
	 */
	public void addQueueListener(String queueDescription,
			QueueListener queueListener) throws QueueTypeNotFoundException,
			QueueException;

	/**
	 * Removes a queueListener from the set of queueListeners of this object.
	 * Passing <CODE>null</CODE> to this method will have no effect.
	 * 
	 * @param queueDescription
	 *            Specify the queue description. e.g.
	 *            "activequeue:queuename;queuesize=10". For this operation, the
	 *            parameter part of the description is meaningless.
	 * @param queueListener
	 *            the observer to be removed.
	 * @throws QueueException
	 *             if there exist some error when removing the queue listener.
	 */
	public void removeQueueListener(String queueDescription,
			QueueListener queueListener) throws QueueException;

	/**
	 * Close specified Queue. If no such Queue was found, this method does
	 * nothing.<br>
	 * User should always call this method to close queue instead of call
	 * close() on queue directly.
	 * 
	 * @param queueDescription
	 *            Specify the queue description. e.g.
	 *            "activequeue:queuename;queuesize=10". For this operation, the
	 *            parameter part of the description is meaningless.
	 * @throws QueueException
	 *             if there exist some error when closing the queue.
	 */
	public void closeQueue(String queueDescription) throws QueueException;
}
